home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat3 / Tk / filehndlr.z / filehndlr
Text File  |  1998-10-30  |  13KB  |  199 lines
  1.  
  2.  
  3.  
  4. TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))                            TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Tk_CreateFileHandler, Tk_CreateFileHandler2, Tk_DeleteFileHandler -
  10.      associate procedure callbacks with files or devices
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
  14.  
  15.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr(_i_d, _m_a_s_k, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  16.  
  17.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr2222(_i_d, _p_r_o_c_2, _c_l_i_e_n_t_D_a_t_a)                             |
  18.  
  19.      TTTTkkkk____DDDDeeeelllleeeetttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr(_i_d)
  20.  
  21. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  22.      int           _i_d           (in)      Integer identifier for an open file
  23.                                           or device (such as returned by ooooppppeeeennnn
  24.                                           system call).
  25.  
  26.      int           _m_a_s_k         (in)      Conditions under which _p_r_o_c should
  27.                                           be called:  OR-ed combination of
  28.                                           TTTTKKKK____RRRREEEEAAAADDDDAAAABBBBLLLLEEEE, TTTTKKKK____WWWWRRRRIIIITTTTAAAABBBBLLLLEEEE, and
  29.                                           TTTTKKKK____EEEEXXXXCCCCEEEEPPPPTTTTIIIIOOOONNNN.
  30.  
  31.      Tk_FileProc   *_p_r_o_c        (in)      Procedure to invoke whenever the
  32.                                           file or device indicated by _i_d meets
  33.                                           the conditions specified by _m_a_s_k.
  34.  
  35.      Tk_FileProc2  *_p_r_o_c_2       (in)      Procedure to invoke from event loop
  36.                                           to check whether _f_d is ready and, if
  37.                                           so, handle it.
  38.  
  39.      ClientData    _c_l_i_e_n_t_D_a_t_a   (in)      Arbitrary one-word value to pass to
  40.                                           _p_r_o_c.
  41.  
  42.  
  43. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  44.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr arranges for _p_r_o_c to be invoked in the future
  45.      whenever I/O becomes possible on a file or an exceptional condition
  46.      exists for the file.  The file is indicated by _i_d, and the conditions of
  47.      interest are indicated by _m_a_s_k.  For example, if _m_a_s_k is TTTTKKKK____RRRREEEEAAAADDDDAAAABBBBLLLLEEEE,
  48.      _p_r_o_c will be called when the file is readable.  The callback to _p_r_o_c is
  49.      made by TTTTkkkk____DDDDooooOOOOnnnneeeeEEEEvvvveeeennnntttt, so TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr is only useful in programs
  50.      that dispatch events through TTTTkkkk____DDDDooooOOOOnnnneeeeEEEEvvvveeeennnntttt or through other Tk procedures
  51.      that call TTTTkkkk____DDDDooooOOOOnnnneeeeEEEEvvvveeeennnntttt, such as TTTTkkkk____MMMMaaaaiiiinnnnLLLLoooooooopppp.
  52.  
  53.      _P_r_o_c should have arguments and result that match the type TTTTkkkk____FFFFiiiilllleeeePPPPrrrroooocccc:
  54.           typedef void Tk_FileProc(
  55.                ClientData _c_l_i_e_n_t_D_a_t_a,
  56.                int _m_a_s_k);
  57.      The _c_l_i_e_n_t_D_a_t_a parameter to _p_r_o_c is a copy of the _c_l_i_e_n_t_D_a_t_a argument
  58.      given to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr when the callback was created.  Typically,
  59.      _c_l_i_e_n_t_D_a_t_a points to a data structure containing application-specific
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))                            TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))
  71.  
  72.  
  73.  
  74.      information about the file.  _M_a_s_k is an integer mask indicating which of
  75.      the requested conditions actually exists for the file;  it will contain a
  76.      subset of the bits in the _m_a_s_k argument to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr.
  77.  
  78.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr2222 also creates a file handler, but it provides a     |
  79.      lower-level and more flexible interface.  The callback procedure _p_r_o_c_2   |
  80.      must have arguments and result that match the following prototype:       |
  81.           typedef int Tk_FileProc2(                                           |
  82.                ClientData _c_l_i_e_n_t_D_a_t_a,                                         |
  83.                int _m_a_s_k,                                                      |
  84.                int _f_l_a_g_s);                                                    |
  85.  
  86.      Whereas a file handler created by TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr is only invoked   |
  87.      when the file is known to be ``ready'', a file handler created by        |
  88.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr2222 is invoked on every pass through the the event loop|
  89.      (TTTTkkkk____DDDDooooWWWWhhhheeeennnnIIIIddddlllleeee); it gets to determine whether the file is ``ready'' or   |
  90.      not.  The _m_a_s_k argument contains an OR'ed combination of the bits        |
  91.      TTTTKKKK____RRRREEEEAAAADDDDAAAABBBBLLLLEEEE, TTTTKKKK____WWWWRRRRIIIITTTTAAAABBBBLLLLEEEE, and TTTTKKKK____EEEEXXXXCCCCEEEEPPPPTTTTIIIIOOOONNNN, which indicate whether the   |
  92.      file is known to be readable, writable, or to have an exceptional        |
  93.      condition present (this is the case if sssseeeelllleeeecccctttt has been invoked since the |
  94.      previous call to _p_r_o_c_2, and if it indicated that the specified conditions|
  95.      were present).  _p_r_o_c_2 may use this information along with additional     |
  96.      information of its own, such as knowledge about buffered data, to decide |
  97.      whether the file is really ``ready''.  The _f_l_a_g_s argument is a copy of   |
  98.      the flags passed to TTTTkkkk____DDDDooooOOOOnnnneeeeEEEEvvvveeeennnntttt, which may be used by _p_r_o_c_2 to ignore  |
  99.      the file if the appropriate bit, such as TTTTKKKK____FFFFIIIILLLLEEEE____EEEEVVVVEEEENNNNTTTTSSSS, is not present. |
  100.  
  101.      _p_r_o_c_2 must return an integer value that is either TTTTKKKK____FFFFIIIILLLLEEEE____HHHHAAAANNNNDDDDLLLLEEEEDDDD or an  |
  102.      OR-ed combination of TTTTKKKK____RRRREEEEAAAADDDDAAAABBBBLLLLEEEE, TTTTKKKK____WWWWRRRRIIIITTTTAAAABBBBLLLLEEEE, and TTTTKKKK____EEEEXXXXCCCCEEEEPPPPTTTTIIIIOOOONNNN.  If the |
  103.      return value is TTTTKKKK____FFFFIIIILLLLEEEE____HHHHAAAANNNNDDDDLLLLEEEEDDDD it means that the file was ``ready'' and |
  104.      that _p_r_o_c_2 handled the ready condition; TTTTkkkk____DDDDooooOOOOnnnneeeeEEEEvvvveeeennnntttt will return        |
  105.      immediately.  If the return value is not TTTTKKKK____FFFFIIIILLLLEEEE____HHHHAAAANNNNDDDDLLLLEEEEDDDD, then it        |
  106.      indicates the set of conditions that should be checked for the file if   |
  107.      the current invocation of TTTTkkkk____DDDDooooWWWWhhhheeeennnnIIIIddddlllleeee invokes sssseeeelllleeeecccctttt.  Typically the   |
  108.      return value reflects all of the conditions that _p_r_o_c_2 cares about.  A   |
  109.      zero return value means that the file should be ignored if TTTTkkkk____DDDDooooWWWWhhhheeeennnnIIIIddddlllleeee |
  110.      calls sssseeeelllleeeecccctttt (this could happen, for example, if the _f_l_a_g_s argument      |
  111.      specified that this file's events should be ignored).  The value returned|
  112.      by _p_r_o_c_2 only affects a sssseeeelllleeeecccctttt call from the current invocation of       |
  113.      TTTTkkkk____DDDDooooOOOOnnnneeeeEEEEvvvveeeennnntttt;  the next invocation of TTTTkkkk____DDDDooooOOOOnnnneeeeEEEEvvvveeeennnntttt will call _p_r_o_c_2     |
  114.      afresh to get new information.
  115.  
  116.      There may exist only one handler for a given file at a given time.  If
  117.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr or TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr2222 is called when a handler
  118.      already exists for _i_d, then the new callback replaces the information
  119.      that was previously recorded.
  120.  
  121.      TTTTkkkk____DDDDeeeelllleeeetttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr may be called to delete the file handler for _i_d;  if
  122.      no handler exists for the file given by _i_d then the procedure has no
  123.      effect.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))                            TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))
  137.  
  138.  
  139.  
  140.      The purpose of file handlers is to enable an application to respond to X
  141.      events and other events while waiting for files to become ready for I/O.
  142.      For this to work correctly, the application may need to use non-blocking
  143.      I/O operations on the files for which handlers are declared.  Otherwise
  144.      the application may be put to sleep if it reads or writes too much data;
  145.      while waiting for the I/O to complete the application won't be able to
  146.      service other events.  In BSD-based UNIX systems, non-blocking I/O can be
  147.      specified for a file using the ffffccccnnnnttttllll kernel call with the FFFFNNNNDDDDEEEELLLLAAAAYYYY flag.
  148.  
  149.  
  150. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  151.      callback, file, handler
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.